DEV Community

PDF Tamper Detection API for C#: ASP.NET Core Integration Guide

Iurii Rogulia — Mon, 03 Aug 2026 10:00:38 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

PDF fraud is a backend problem, and in enterprise fintech a great deal of that backend runs on .NET. An ASP.NET Core service ingests an uploaded bank statement, a payslip, or a claim packet, writes a row, and hands the document to underwriting — and by the time your controller has returned 201 Created, the document’s claims have already propagated into your business logic. Your KYC provider confirmed the applicant is a real person with a valid identity. It said nothing about whether the PDF they uploaded was edited after the bank generated it. That structural-tampering layer is invisible to identity verification, and the right place to catch it is at ingress: before your service trusts the file, not after.

This guide walks through integrating the PDF tamper detection API into an ASP.NET Core application — from the first curl command to an idiomatic typed HtpbeClient built on IHttpClientFactory, with System.Text.Json record DTOs, configuration-bound options for the API key, polling with backoff, error handling that distinguishes a configuration failure from a transient one, and a small bank-statement gate that decides accept / reject / review. The patterns target .NET 8 (the current LTS) and use minimal APIs, but everything maps cleanly to a controller-based project. Treat the code as a reference architecture — it runs the real request flow against the documented error codes, but you should adapt and harden it for your own traffic profile and threat model. (If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. Integrating from another stack? See the Java / Spring Boot, Go, Node.js, Python, and Laravel / PHP guides.)

TL;DR

Two API calls, three verdicts: POST /analyze returns a top-level id, then GET /result/{id} returns the flat verdict object whose status is one of intact, modified, or inconclusive.
The minimum integration is a typed HttpClient and two awaited calls. No dependency beyond the framework and System.Text.Json.
Production shape: an HtpbeClient typed client registered with IHttpClientFactory, record DTOs with snake_case naming, a custom exception carrying the status code, and a Polly retry policy that backs off on 5xx and 429 only.
A DocumentGate that maps the three verdicts to an Accept / Reject / Review decision for documents that claim institutional origin.
This is structural PDF tamper and forgery detection — not KYC, not OCR, not AI-text detection. It complements an identity stack; it does not replace one.

Prerequisites

.NET 8 SDK (records, required members, IHttpClientFactory, minimal APIs)
An HTPBE API key (Dashboard → copy key)
Optionally Microsoft.Extensions.Http.Polly for the resilience policy in Step 6 (the framework HttpClient works without it)

Step 1: Test the API with curl

Before writing any C#, confirm your key works. The API uses a two-step flow: POST /analyze submits a PDF URL and returns a check id, then GET /result/{id} retrieves the full verdict. (For a language-agnostic overview of what the API detects, see how PDF tamper detection works.)

Step 1a — submit for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

You will receive a flat object with a single field: {"id": "00000000-0000-4000-8000-000000000001"}

Step 1b — retrieve the result:

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

You will receive a flat JSON object with "status": "intact" and the full set of analysis fields:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "filename": "clean.pdf",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

The same shape comes back for modified and inconclusive verdicts — only the values change. Two fields are conditional: status_reason appears only when status is inconclusive, and outdated_warning only when the check ran against an older algorithm version. Note that there is no data wrapper and no numeric risk score — the response is the flat object above, and the whole signal is the verdict plus the named markers.

The URL https://api.htpbe.tech/v1/test/clean.pdf is a test mock — it returns a predictable response without consuming quota. Test keys (prefix htpbe_test_) accept only these mock URLs; live keys (prefix htpbe_live_) accept any public PDF URL.

Step 2: Bind Configuration, Not Constants

Keep the key and base URL out of code. Bind them to a typed options record so they are validated at startup and overridable per environment. The key resolves from configuration — appsettings.json, an environment variable, or a secrets store — never a hard-coded literal.

namespace Htpbe;

public sealed class HtpbeOptions
{
    public const string SectionName = "Htpbe";

    public required string ApiKey { get; init; }
    public string BaseUrl { get; init; } = "https://api.htpbe.tech/v1/";
    public int TimeoutSeconds { get; init; } = 35;
    public int MaxResultPollAttempts { get; init; } = 5;
}

Provide the values in appsettings.json, leaving the key itself empty so it is supplied by an environment variable or user-secret at runtime:

{
  "Htpbe": {
    "ApiKey": "",
    "BaseUrl": "https://api.htpbe.tech/v1/",
    "TimeoutSeconds": 35,
    "MaxResultPollAttempts": 5
  }
}

In development, store the key with dotnet user-secrets set "Htpbe:ApiKey" "htpbe_live_...". In production, set the environment variable Htpbe__ApiKey (the double underscore maps to the nested section). Either way the key never lands in source control. Bind and validate the options in Program.cs so a missing key fails the application at boot, not on the first document that arrives at 2 a.m.:

builder.Services
    .AddOptions<HtpbeOptions>()
    .Bind(builder.Configuration.GetSection(HtpbeOptions.SectionName))
    .Validate(o => !string.IsNullOrWhiteSpace(o.ApiKey),
        "Htpbe:ApiKey is not configured. Set the Htpbe__ApiKey environment variable.")
    .ValidateOnStart();

Step 3: The Result DTO

Model the GET /result/{id} response as C# records. System.Text.Json maps snake_case JSON to PascalCase members when you set JsonNamingPolicy.SnakeCaseLower on the serializer options (available since .NET 8). Reference types stay nullable so “absent” remains distinguishable from a genuine zero, and unknown fields are ignored by default so a newly added API field never breaks deserialization.

using System.Text.Json.Serialization;

namespace Htpbe;

public sealed record AnalysisResult
{
    public required string Id { get; init; }
    public string? Filename { get; init; }
    public long? FileSize { get; init; }
    public int? PageCount { get; init; }

    public string? AlgorithmVersion { get; init; }
    public string? CurrentAlgorithmVersion { get; init; }
    public string? OutdatedWarning { get; init; } // present only on an outdated check

    // Primary verdict: "intact" | "modified" | "inconclusive"
    public required string Status { get; init; }

    // Present only when Status == "inconclusive":
    // "consumer_software_origin" | "online_editor_origin" |
    // "scanned_document" | "unverifiable_metadata"
    public string? StatusReason { get; init; }

    public Origin? Origin { get; init; }

    // "certain" | "high" | "none" | null
    public string? ModificationConfidence { get; init; }

    public string? Creator { get; init; }
    public string? Producer { get; init; }
    public long? CreationDate { get; init; }     // Unix seconds
    public long? ModificationDate { get; init; } // Unix seconds
    public string? PdfVersion { get; init; }

    public bool DateSequenceValid { get; init; }
    public int MetadataCompletenessScore { get; init; }

    public int XrefCount { get; init; }
    public bool HasIncrementalUpdates { get; init; }
    public int UpdateChainLength { get; init; }

    public bool HasDigitalSignature { get; init; }
    public int SignatureCount { get; init; }
    public bool SignatureRemoved { get; init; }
    public bool ModificationsAfterSignature { get; init; }

    public int ObjectCount { get; init; }
    public bool HasJavascript { get; init; }
    public bool HasEmbeddedFiles { get; init; }

    // Stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"].
    // Empty when Status is "intact" or "inconclusive".
    public IReadOnlyList<string> ModificationMarkers { get; init; } = [];

    [JsonIgnore] public bool IsIntact => Status == "intact";
    [JsonIgnore] public bool IsModified => Status == "modified";
    [JsonIgnore] public bool IsInconclusive => Status == "inconclusive";
}

public sealed record Origin
{
    // "consumer_software" | "institutional" | "unknown" |
    // "online_editor" | "scanned"
    public string? Type { get; init; }
    public string? Software { get; init; }
}

// The /analyze response carries only the check id.
public sealed record AnalyzeResponse
{
    public required string Id { get; init; }
}

Two fields deserve a closer look. StatusReason is populated only when Status is inconclusive, and it carries one of several values — consumer_software_origin, online_editor_origin, scanned_document, and a few more. The difference matters: a scanned document is benign for a user-submitted handwritten form, but a consumer_software_origin on something that claims to be a payslip is the kind of origin you would not expect from a real payroll system — that class covers both consumer apps and freely available HTML-to-PDF renderers, so it is a strong signal to route for review. Branch on the specific reason, not just on the top-level inconclusive.

ModificationMarkers returns stable, machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_POST_SIGNATURE_EDIT, HTPBE_MULTIPLE_REVISION_LAYERS. Branch your integration logic on the id; render the human-readable label from the dictionary published on htpbe.tech/how. These ids are part of the public contract and never change once shipped. The API does not return a numeric risk score — the verdict plus the named markers are the whole signal, by design, so there is no threshold to tune on your side.

A small enum keeps the rest of your codebase from comparing against bare string literals:

namespace Htpbe;

public enum Verdict { Intact, Modified, Inconclusive }

public static class VerdictParser
{
    public static Verdict Parse(string status) => status switch
    {
        "intact" => Verdict.Intact,
        "modified" => Verdict.Modified,
        "inconclusive" => Verdict.Inconclusive,
        _ => throw new ArgumentOutOfRangeException(
            nameof(status), status, "unknown status from HTPBE"),
    };
}

Step 4: A Typed Exception

A 401 means your key is wrong; a 402 means the credit pool is dry; a 500 is transient. Both the retry layer and your business logic need to branch on the status code, so wrap every non-success response in a typed exception that carries it.

namespace Htpbe;

public sealed class HtpbeApiException : Exception
{
    public int StatusCode { get; }
    public string Code { get; }                 // machine-readable code from the JSON body
    public int? RetryAfterSeconds { get; }      // parsed from Retry-After on 429; null if absent

    public HtpbeApiException(int statusCode, string code, string message, int? retryAfterSeconds = null)
        : base($"htpbe: {statusCode} {code}: {message}")
    {
        StatusCode = statusCode;
        Code = code;
        RetryAfterSeconds = retryAfterSeconds;
    }

    // Only 5xx and 429 are transient. Every other 4xx is permanent —
    // retrying it burns latency and, for 402, can never succeed until
    // the account is topped up.
    public bool Retryable => StatusCode >= 500 || StatusCode == 429;
}

Step 5: The Typed HttpClient

Here is the complete client. It is a typed HttpClient — registered with IHttpClientFactory in Step 6 — so the factory owns the connection pool and the Authorization header is set once at registration. The client exposes one public method, VerifyAsync, that runs both steps of the flow; a private ParseErrorAsync converts every non-success response into an HtpbeApiException, reading the JSON error body and the Retry-After header in one place.

using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Extensions.Options;

namespace Htpbe;

public sealed class HtpbeClient
{
    private readonly HttpClient _http;
    private readonly int _maxPollAttempts;

    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
        PropertyNameCaseInsensitive = true,
    };

    public HtpbeClient(HttpClient http, IOptions<HtpbeOptions> options)
    {
        _http = http;
        _maxPollAttempts = options.Value.MaxResultPollAttempts;
    }

    /// <summary>
    /// Submits a PDF URL and returns the full verdict. The two steps are kept
    /// separate on purpose: POST /analyze is the billable, job-creating call,
    /// GET /result/{id} is a free read. The resilience policy (Step 6) wraps
    /// the whole client, but only transient failures are retried — a permanent
    /// 402 short-circuits immediately.
    /// </summary>
    public async Task<AnalysisResult> VerifyAsync(
        string pdfUrl, string? originalFilename = null, CancellationToken ct = default)
    {
        var id = await SubmitAnalysisAsync(pdfUrl, originalFilename, ct);
        return await GetResultAsync(id, ct);
    }

    private async Task<string> SubmitAnalysisAsync(
        string pdfUrl, string? originalFilename, CancellationToken ct)
    {
        // The API accepts a JSON body with the PDF URL; original_filename is optional.
        var body = originalFilename is null
            ? new Dictionary<string, string> { ["url"] = pdfUrl }
            : new Dictionary<string, string> { ["url"] = pdfUrl, ["original_filename"] = originalFilename };

        using var response = await _http.PostAsJsonAsync("analyze", body, JsonOptions, ct);

        if (!response.IsSuccessStatusCode)
            throw await ParseErrorAsync(response, ct);

        var payload = await response.Content.ReadFromJsonAsync<AnalyzeResponse>(JsonOptions, ct);
        if (payload is null || string.IsNullOrEmpty(payload.Id))
            throw new HtpbeApiException(502, "BAD_RESPONSE", "analyze response missing id");

        return payload.Id;
    }

    private async Task<AnalysisResult> GetResultAsync(string id, CancellationToken ct)
    {
        // POST /analyze runs the analysis synchronously, so the result is normally
        // ready on the first GET. The bounded poll below is defensive: it tolerates
        // a brief replication lag and re-reads on a transient 404 before giving up.
        HtpbeApiException? lastError = null;

        for (var attempt = 1; attempt <= _maxPollAttempts; attempt++)
        {
            using var response = await _http.GetAsync($"result/{id}", ct);

            if (response.IsSuccessStatusCode)
            {
                var result = await response.Content.ReadFromJsonAsync<AnalysisResult>(JsonOptions, ct);
                return result ?? throw new HtpbeApiException(502, "BAD_RESPONSE", "empty result body");
            }

            lastError = await ParseErrorAsync(response, ct);

            // Only a 404 is worth re-reading (the row may not be visible yet).
            // Every other error is terminal — surface it without burning attempts.
            if (response.StatusCode != HttpStatusCode.NotFound)
                throw lastError;

            await Task.Delay(TimeSpan.FromMilliseconds(300 * attempt), ct);
        }

        throw lastError ?? new HtpbeApiException(504, "RESULT_TIMEOUT", "result not ready after polling");
    }

    private static async Task<HtpbeApiException> ParseErrorAsync(
        HttpResponseMessage response, CancellationToken ct)
    {
        var statusCode = (int)response.StatusCode;
        var code = "UNKNOWN";
        var message = response.ReasonPhrase ?? statusCode.ToString();

        try
        {
            var error = await response.Content.ReadFromJsonAsync<ErrorBody>(JsonOptions, ct);
            if (error is not null)
            {
                code = error.Code ?? code;
                message = error.Error ?? message;
            }
        }
        catch (JsonException)
        {
            // body was not JSON — keep the status-derived defaults
        }

        message = statusCode switch
        {
            401 => "invalid API key — check Htpbe:ApiKey",
            402 => "no credits available for this key — top up or subscribe",
            403 => "test key sent to a live URL, or vice versa",
            413 => "PDF exceeds the 10 MB size limit",
            422 => "the URL did not return a valid PDF file",
            _ => message,
        };

        int? retryAfter = null;
        if (statusCode == 429 && response.Headers.RetryAfter is { } ra)
            retryAfter = ParseRetryAfter(ra);

        return new HtpbeApiException(statusCode, code, message, retryAfter);
    }

    // Handles both the delta-seconds form and the HTTP-date form,
    // clamped to [1, 600]. Returns null when neither is present.
    private static int? ParseRetryAfter(System.Net.Http.Headers.RetryConditionHeaderValue ra)
    {
        if (ra.Delta is { } delta)
            return Math.Clamp((int)delta.TotalSeconds, 1, 600);
        if (ra.Date is { } date)
            return Math.Clamp((int)(date - DateTimeOffset.UtcNow).TotalSeconds, 1, 600);
        return null;
    }

    private sealed record ErrorBody
    {
        public string? Error { get; init; }
        public string? Code { get; init; }
    }
}

Two status codes deserve explicit handling in your own code:

402 (Payment Required) — the key has no credit source left. Credits are universal: a subscription’s monthly quota, a one-time top-up batch, and the welcome credits all draw from one pool. A 402 means all three are exhausted (or there is no active plan on a live key). HtpbeApiException.Retryable returns false for it — surface it to your billing path rather than retrying, because retrying fails identically until the account is topped up at the pricing page.
429 (Too Many Requests) — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header, which ParseRetryAfter reads (both delta-seconds and HTTP-date forms, clamped to [1, 600]) and stashes on the exception. Your retry policy reads that value before falling back to exponential backoff.

Step 6: Register the Client and Retry on Transient Failures Only

Register HtpbeClient as a typed client. IHttpClientFactory manages the underlying handler pool, sets the base address and default headers once, and lets you attach a resilience policy. The policy retries only on the transient codes — 5xx and 429 — and never on the permanent 4xx codes like 401, 402, or 422, where retrying would burn latency and credits without ever succeeding.

using System.Net;
using Microsoft.Extensions.Options;
using Polly;
using Polly.Extensions.Http;

// In Program.cs

builder.Services
    .AddHttpClient<HtpbeClient>((sp, http) =>
    {
        var opts = sp.GetRequiredService<IOptions<HtpbeOptions>>().Value;
        http.BaseAddress = new Uri(opts.BaseUrl);
        http.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", opts.ApiKey);
        http.DefaultRequestHeaders.Accept.Add(
            new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
        http.Timeout = TimeSpan.FromSeconds(opts.TimeoutSeconds);
    })
    .AddPolicyHandler(TransientRetryPolicy());

static IAsyncPolicy<HttpResponseMessage> TransientRetryPolicy() =>
    HttpPolicyExtensions
        // Network failures and 5xx are handled by HandleTransientHttpError;
        // add 429 explicitly so a capacity signal also backs off and retries.
        .HandleTransientHttpError()
        .OrResult(r => r.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(
            retryCount: 3,
            sleepDurationProvider: (attempt, response, _) =>
            {
                // Honour a server-supplied Retry-After when present (429 capacity),
                // otherwise fall back to exponential backoff: 1s, 2s, 4s.
                var retryAfter = response.Result?.Headers.RetryAfter?.Delta;
                return retryAfter ?? TimeSpan.FromSeconds(Math.Pow(2, attempt - 1));
            },
            onRetryAsync: (_, _, _, _) => Task.CompletedTask);

If you would rather not take a Polly dependency, the bounded poll inside GetResultAsync already handles the most common transient case (a result that is not yet visible), and you can wrap VerifyAsync in a small for loop that re-throws when HtpbeApiException.Retryable is false. For most integrations the Polly handler is the cleanest fit, because it sits at the HttpClient layer and applies to both the submit and the read uniformly.

Step 7: The Bank-Statement Gate

The client returns facts. Turning those facts into an Accept / Reject / Review decision is a policy choice that depends on what the document claims to be. A bank statement, a payslip, or a diploma claims institutional origin, so anything other than intact should stop the automated path. A user-generated form is held to a looser standard.

namespace Htpbe;

public enum Decision { Accept, Reject, Review }

public static class DocumentGate
{
    /// <summary>
    /// Maps a verdict to a decision for documents that claim institutional
    /// origin (bank statements, payslips, diplomas). For these, "inconclusive"
    /// is treated as strictly as "modified": a document that should have come
    /// from a bank's own system but looks like it was built in Word does not
    /// get the benefit of the doubt.
    /// </summary>
    public static Decision ForInstitutional(AnalysisResult r) =>
        VerdictParser.Parse(r.Status) switch
        {
            Verdict.Modified => Decision.Reject,
            // A bank statement that comes back inconclusive should not be
            // auto-accepted: it typically came from consumer software rather
            // than a bank's own system — a signal to route for review, not
            // proof of tampering. Send it to a human.
            Verdict.Inconclusive => Decision.Review,
            Verdict.Intact => Decision.Accept,
            _ => Decision.Review,
        };
}

Wire the client and the gate into a minimal-API endpoint that accepts a JSON body with a reachable URL. The handler runs the check before any business logic touches the file:

// In Program.cs, after building the app

app.MapPost("/api/documents/verify", async (
    VerifyRequest req, HtpbeClient client, CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(req.DocumentUrl))
        return Results.BadRequest(new { error = "documentUrl is required" });

    AnalysisResult result;
    try
    {
        result = await client.VerifyAsync(req.DocumentUrl, req.OriginalFilename, ct);
    }
    catch (HtpbeApiException e)
    {
        return MapApiError(e);
    }

    return DocumentGate.ForInstitutional(result) switch
    {
        Decision.Reject => Results.UnprocessableEntity(new
        {
            decision = "reject",
            reason = "document modified after creation",
            modification_markers = result.ModificationMarkers,
        }),
        Decision.Review => Results.Accepted(value: new
        {
            decision = "review",
            status_reason = result.StatusReason,
        }),
        _ => Results.Ok(new { decision = "accept", check_id = result.Id }),
    };
});

static IResult MapApiError(HtpbeApiException e) => e.StatusCode switch
{
    // Configuration / billing errors — never leak the cause to the caller.
    401 or 402 => Results.Problem(
        "verification temporarily unavailable", statusCode: 503),
    422 => Results.UnprocessableEntity(
        new { error = "the URL did not return a valid PDF" }),
    413 => Results.Problem("PDF must be under 10 MB", statusCode: 413),
    _ => Results.Problem("verification failed", statusCode: 502),
};

public sealed record VerifyRequest(string DocumentUrl, string? OriginalFilename);

An inconclusive result should not be auto-accepted — it typically indicates the file came from consumer software, an online editor, an HTML renderer, or a scanner rather than an institutional generator. That is a signal to route for review, not proof of tampering. For a deeper explanation, see what “inconclusive” really means. For documents that claim institutional origin, treat inconclusive with the same caution as modified: do not accept automatically, route to a human reviewer. Inverting that policy — treating inconclusive as a pass — is the single most common integration mistake, because it hands an automatic accept to exactly the consumer-software-built documents a bank statement should never be.

Step 8: Giving the API a Reachable URL

The API does not accept file uploads — it downloads the PDF from a URL you supply, so the file must be publicly reachable for the few seconds the analysis takes. The cleanest pattern is a short-lived presigned URL from your object store: you never expose the bucket, the link expires in minutes, and passing originalFilename keeps the audit trail readable instead of showing an opaque storage key.

// Store the upload privately, mint a 5-minute presigned GET URL, verify.
var key = $"incoming/{Guid.NewGuid()}.pdf";

await s3.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = key,
    InputStream = pdfStream,
    ContentType = "application/pdf",
}, ct);

var presignedUrl = await s3.GetPreSignedURLAsync(new GetPreSignedUrlRequest
{
    BucketName = bucket,
    Key = key,
    Expires = DateTime.UtcNow.AddMinutes(5),
    Verb = HttpVerb.GET,
});

var result = await client.VerifyAsync(presignedUrl, originalFilename, ct);

The same pattern works with Azure Blob Storage (a SAS token via BlobClient.GenerateSasUri), Google Cloud Storage (UrlSigner), or Cloudflare R2 (S3-compatible — reuse the AWS SDK with the R2 endpoint). One security note: the API fetches whatever URL you give it, so if a URL ever comes from untrusted input (a user-pasted link, a webhook payload), validate that it resolves to a public host first — reject localhost, 169.254.169.254 (cloud metadata), and the RFC 1918 private ranges to close the SSRF surface. When you mint the URL yourself from a private bucket the risk is minimal, but the validation belongs in the request flow either way.

Step 9: Testing Without Burning Quota

Every plan includes a test API key (prefix htpbe_test_) that accepts only mock URLs of the form https://api.htpbe.tech/v1/test/{filename}.pdf and returns deterministic responses — like Stripe test cards, with no quota cost. Point an integration test at these fixtures to cover every branch of the gate. With WebApplicationFactory<Program> you exercise the real HtpbeClient, configured with the test key:

using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.Extensions.DependencyInjection;
using Xunit;

public sealed class HtpbeClientTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HtpbeClient _client;

    public HtpbeClientTests(WebApplicationFactory<Program> factory)
    {
        var configured = factory.WithWebHostBuilder(builder =>
            builder.UseSetting("Htpbe:ApiKey",
                Environment.GetEnvironmentVariable("HTPBE_TEST_API_KEY")!));
        _client = configured.Services.GetRequiredService<HtpbeClient>();
    }

    [Fact]
    public async Task CleanDocumentReturnsIntact()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/clean.pdf");

        Assert.Equal("intact", r.Status);
        Assert.Empty(r.ModificationMarkers);
        Assert.Equal(Decision.Accept, DocumentGate.ForInstitutional(r));
    }

    [Fact]
    public async Task SignatureRemovedIsRejected()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/signature-removed.pdf");

        Assert.Equal("modified", r.Status);
        Assert.True(r.SignatureRemoved);
        Assert.Equal(Decision.Reject, DocumentGate.ForInstitutional(r));
    }

    [Fact]
    public async Task InconclusiveIsRoutedToReview()
    {
        var r = await _client.VerifyAsync("https://api.htpbe.tech/v1/test/inconclusive.pdf");

        Assert.Equal("inconclusive", r.Status);
        Assert.NotNull(r.StatusReason);
        Assert.Equal(Decision.Review, DocumentGate.ForInstitutional(r));
    }
}

Useful fixtures: clean.pdf → intact, signature-removed.pdf → modified, dates-mismatch.pdf → modified, and inconclusive.pdf → inconclusive. For pure unit tests of the endpoint and gate without any network, inject a fake HttpMessageHandler into the HtpbeClient and return canned JSON, or test DocumentGate.ForInstitutional directly against a hand-built AnalysisResult. Keep test and live keys in separate configuration sources and never commit either.

For audit dashboards, GET /api/v1/checks returns a paginated list of every result for your key — filter by status and limit (/checks?status=modified&limit=50, same Authorization header). When you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until it resets — add a one-time credit pack or move to a higher tier to keep going, and handle the 402 so a quota boundary never silently drops a check.

What the Verdicts Mean

The whole signal is three verdicts and a list of named markers. Encoding them correctly in your DocumentGate matters more than any other choice in the integration:

intact — no post-creation modification was detected and the origin looks institutional. Safe to accept on the automated path.
modified — forensic evidence of an edit after the document was created. The modification_markers array names the signal: HTPBE_DATES_DISAGREE for inconsistent internal timestamps, HTPBE_SIGNATURE_REMOVED for a stripped digital signature, HTPBE_POST_SIGNATURE_EDIT for changes made after signing, HTPBE_MULTIPLE_REVISION_LAYERS for a document saved repeatedly after creation. Reject, or route to fraud review.
inconclusive — the document was built with consumer software, an online editor, an HTML renderer, or a scanner, so there is no institutional “original” to verify integrity against. This is not a failure and not a clean pass — it is a routing signal. For a document that should have come from an institution (a bank statement, a payslip), inconclusive means it did not, which is exactly why DocumentGate.ForInstitutional routes it to a human reviewer.

What This Does Not Catch

Structural analysis has honest limits, and an ASP.NET Core service making automated decisions should encode them rather than overstate the verdict:

Content fabricated in one pass. If someone opens Word, types a false salary, and exports once, the file was never modified after creation — it is structurally consistent. The fraud happened at authorship, not at the byte level. This is exactly why a payslip from a consumer tool tends to return inconclusive rather than intact: the analysis cannot vouch for a document anyone could have produced from scratch.
Born-synthetic forgeries. A fake document generated programmatically with a valid-looking account number and a real logo — never derived from a genuine original — has no post-creation edit to detect. Catching that is a content-verification problem (does this account number exist, does this employer match payroll records), a different product category from structural tamper detection.
Documents rebuilt from scratch in the original’s software. A determined attacker who recreates a document in the same institutional tool and matches the metadata leaves few structural signals. This is rare and high-effort, but possible.
Encrypted or password-protected PDFs. The service cannot parse a file it cannot open; remove the password before submitting.

These limits are why structural tamper detection works as one layer in a fraud-detection stack, not the whole stack. Pair the structural verdict with domain checks — amount validation, account-number lookups, sender authentication, and your KYC or OCR provider — for a layered defense. The structural layer answers a question identity verification cannot: was this file edited after it was issued? See PDF Fraud Prevention Best Practices.

Decisions Before You Ship

The integration surface is intentionally small: one POST, one GET, three verdicts, the typed exception above. The complexity lives on the .NET side, and two choices matter most:

Where verification runs. Synchronous inside the request handler gives the caller an immediate decision but blocks for a few seconds; a background IHostedService or a message-driven consumer (Azure Service Bus, RabbitMQ) returns instantly and defers the verdict. Sync suits low-volume B2B onboarding; async suits high-volume portals. Because the call is fully async/await and the analysis takes 2–5 seconds, the synchronous path is cheap enough for most onboarding flows.
inconclusive routing. For documents that claim institutional origin (bank statements, diplomas, payslips), treat inconclusive with the same caution as modified and route to human review — that is what DocumentGate.ForInstitutional encodes. For genuinely user-generated content it may be acceptable as-is, so you may want a second gate with a looser policy.

To start, sign up for HTPBE — new accounts get five checks to try, then pay-per-check credits or a subscription (see current pricing) — copy your test key, and run the curl call from Step 1. The full API reference documents every response field, error code, and the marker dictionary the .NET client branches on.

Building Coordination Infrastructure: What 32 MCP Servers Without a Bus Look Like

Gabriel Mahia — Mon, 03 Aug 2026 10:00:00 +0000

Thirty-two MCP servers for Kenya's coordination domains.

Water. Health. Agriculture. Insurance. Land. Education. Transport. Tax. Labor. Market prices.

Each one works. None talks to any other.

This is what 32 isolated tools looks like in practice: a CHW in Kisumu flags a cholera cluster. The water quality system doesn't know. The county procurement system doesn't know. The emergency medicine supply chain doesn't know. The tools that need to respond are all present. The coordination between them doesn't exist.

The architectural problem

The Model Context Protocol ecosystem is growing fast. For most of the world, it's growing in domains that already have coordination infrastructure: calendar apps, email clients, project management tools. These tools coordinate with each other through years of API integrations, webhooks, Zapier connections, and shared data stores.

African coordination domains don't have that legacy. They're being built now, from scratch, on MCP.

That means the coordination layer has to be built at the same time.

What a coordination layer looks like at the MCP level

africa-coord-bus defines a CoordinationEvent — a standard cross-domain signal schema — and an EventBus that routes events to the tools that need to respond.

The routing table is explicit:

Trigger	Cascade
`water.drought_alert` (Warning+)	bima-mcp, kilimo-mcp, soko-mcp
`water.drought_alert` (Alert+)	+ afya-mcp, county-mcp
`health.disease_outbreak` (cholera)	wapimaji-mcp water quality check
`agriculture.price_spike` (>30%)	afya-mcp food security watch
`water.flood_alert`	afya-mcp waterborne watch, county-mcp

Custom rules take three lines:

from africa_coord_bus import RoutingRule, EventDomain, EventSeverity

bus.routing.add(RoutingRule(
    name="locust→emergency_procurement",
    trigger_domain=EventDomain.AGRICULTURE,
    trigger_event_type="locust_swarm",
    trigger_min_severity=EventSeverity.ALERT,
    target_actions=["fomu-mcp.emergency_procurement", "county-mcp.agriculture_alert"],
))

The composable coordination stack

The pattern that's emerging for East Africa:

Public domain datasets (HuggingFace)
        │ grounding knowledge
        ▼
32 MCP servers (PyPI) ←── africa-coord-bus
        │
        ▼
A2A + ADK agents
        │
        ▼
Streamlit coordination interfaces

Each layer is replaceable. The models are replaceable. The MCP servers are replaceable. What persists is the coordination architecture.

Install

pip install africa-coord-bus

Source: github.com/gabrielmahia/africa-coord-bus

The coordination gap was the last missing layer. It's now installable.

Source: africa-coord-bus on PyPI

Still Testing APIs Like It's 2022? Here's Everything That Changed"

Imran Al Munyeem — Mon, 03 Aug 2026 10:00:00 +0000

If you learnt Postman a few years ago and have been coasting on that knowledge, an uncomfortable amount of it is now wrong — not "slightly dated" wrong, but "the tab you're looking for doesn't exist" wrong.

I know because I wrote a Postman guide in 2022 and recently rewrote it as a full book. Here's the changelog of everything that broke, moved, or appeared — the field guide I wish I'd had.

1. The Tests tab is gone

The old Tests and Pre-request Script tabs were merged into a single Scripts tab with two sections: Pre-request (runs before the request) and Post-response (runs after — this is where your tests live now).

Your code is unchanged — same pm.test, same Chai assertions, same snippets — only the geography moved:

// Exactly the same as it ever was, just under Scripts → Post-response
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

Every tutorial screenshot showing a Tests tab is from the old world. The concepts transfer completely.

2. Newman has an official successor

Newman — the beloved open-source CLI runner — is no longer the only way to run collections from a terminal. The official Postman CLI authenticates with a Postman API key and can run collections straight from your workspace, no export step:

postman login --with-api-key $POSTMAN_API_KEY
postman collection run 12345678-abcd-efgh-ijkl-9876543210ab

It also pushes results back to Postman's cloud as a shareable run report.

Newman still works fine and its htmlextra HTML reports remain unmatched — but there's a hard compatibility line to know: Newman only supports collection format v2/v2.1. Postman v12 introduced a v3 (YAML) format for its Git-native workflows, and Newman cannot run it. New pipeline? Start with the Postman CLI. Existing Newman pipeline? It keeps working — just export v2.1.

3. Your Jenkins tutorial will not work

The classic "install JDK 8, run java -jar jenkins.war" instructions are dead: modern Jenkins requires Java 21 (recent LTS lines dropped Java 17 and older). If you're standing up a CI box today, grab Temurin 21 from adoptium.net first, or Jenkins simply won't start.

Better yet, notice that for many teams the Jenkins box is now optional — a 25-line GitHub Actions workflow runs your collection on every push and every night, with no server to patch:

name: API Tests
on:
  push:
  schedule:
    - cron: "0 2 * * *"
jobs:
  postman-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
      - run: npm install -g newman newman-reporter-htmlextra
      - run: newman run collections/MyCollection.postman_collection.json -r cli,htmlextra

4. There's an AI in the footer

Postbot generates tests from plain-English prompts, adds baseline tests to a whole collection in one action, repairs failing scripts, documents requests, and visualises responses. It's genuinely useful and genuinely dangerous in the same specific way: it writes assertions from the response your API currently gives — so if the current behaviour is a bug, the bug becomes the expected result. Generate freely; review against the spec, not the response. (I wrote a whole piece on this failure mode.)

Postman also added AI request types (test your LLM-backed endpoints like any other), Agent Mode, and an MCP server — the platform is clearly betting that agents will be first-class API consumers.

5. Your practice APIs died

Heroku ended its free tier, taking a generation of tutorial APIs with it. If a guide points you at something.herokuapp.com, expect a dead link. JSONPlaceholder (jsonplaceholder.typicode.com) remains free, signup-less, and reliable — or create a mock server inside Postman itself from your saved examples.

6. The scripting API moved on politely

postman.setNextRequest(null) still works, but the current form is:

pm.execution.setNextRequest(null);   // stop the run
pm.execution.setNextRequest("Delete user");   // or jump to a request

Same story across the pm API: old code keeps running, new code should use the new names.

7. Secrets got first-class treatment

Two things every team should know: variables now have a secret type (masked on screen), and — the one that catches people — initial values sync to Postman's servers and are shared with collaborators, while current values stay on your machine. Real credentials go in current values only, or in Postman Vault (encrypted, local, never synced). The classic leak is a Bearer token pasted into an initial value "just for a second," then synced, then forked into a public workspace.

The takeaway

None of this changed what good API testing is — five layers of assertions, negative cases, deterministic suites, CI enforcement. What changed is the tooling around it, and the tooling changed enough that 2022 muscle memory now produces broken pipelines and missing tabs. Update the muscle memory; keep the principles.

This is the story behind my free, open-source book *API Testing Using Postman: The Practical Guide to Modern API Testing** — a 2022 guide rewritten end-to-end for how we test now. Read online, grab the PDF/EPUB, or contribute on GitHub.*

I'm a PhD researcher in Computer Science at Nottingham Trent University working on cybersecurity and AI-assisted security testing. More at imranalmunyeem.com.

From Retrospective Liability to Proactive Capability — A Path to Crypto-Agility and Compliance with Embedded Security Requirements

Art Keller — Mon, 03 Aug 2026 09:55:51 +0000

NON-PAPER

This paper is distributed solely for discussion purposes. It reflects an independent analytical perspective and is not presented on behalf of any organization, body, or regulatory authority.

1. Setting the Context

The convergence of the EU Cyber Resilience Act, NIS2, DORA, and national implementations such as BSI TR-02102 creates a compliance landscape for which many organizations with long-standing embedded product lines are structurally unprepared - not due to a lack of technical solutions, but due to a lack of a common approach that integrates technical capability, budgetary autonomy, and risk appetite into a single, actionable timeline.

This is not a failure of any single function, company, or industry. It is the predictable result of three decades of technological decisions, each made under different circumstances, that are now converging on a regulatory deadline that does not distinguish between historical legacy issues and current negligence. Treating this convergence as a blame game is counterproductive: it encourages concealment over disclosure and inaction over incremental progress.

2. Diagnosis, Without Blame

Three institutional patterns recur across organizations, regardless of industry or size:

Technical knowledge of exposure (legacy silicon without cryptographic isolation, insufficient memory for PQC migration, lack of side-channel protection) typically exists long before action is taken - the gap lies in decision-making authority and funding, not in awareness.
Risk-averse institutional behavior, when acting rationally within the framework of its own incentives, tends to discourage disclosure rather than facilitate remediation, since disclosure without a funded remediation plan creates risk without offering corresponding risk mitigation.
Capital allocation processes designed for predictable, limited costs receive compliance issues reported either as “resolved” (which underestimates the residual risk) or as “critical” (without actionable cost or time estimates) - both of which are poor bases for decision-making.

The result is a structural stalemate: Each pattern is rational in and of itself, and the overall result is stagnation.

3. The Manufacturing Dimension: Disruption as Capital Destruction

For manufacturing companies - particularly in the Industry 4.0 context, where product lines are tied to long depreciation cycles, specialized supply chains, and capital-intensive tooling - this stalemate takes on a specific and more acute form.

The prevailing vocabulary surrounding compliance-driven technological change draws heavily on the term “disruption” - a term that became popular to describe market entry, not asset management. When applied to an existing inventory of manufacturing equipment or industrial products in the field, disruption is not a neutral or even positive event:
It is the forced write-off of capital that has not yet reached its intended useful life. A product discontinuation triggered by the inability to meet a cryptographic compliance deadline is not innovation - it is the destruction of prior investments, often exacerbated by the costs of a rushed replacement cycle carried out without the lead time such transitions typically require.

This distinction is important because it changes the nature of the decision facing manufacturing companies. The choice is not “innovate or stagnate” - the framing suggested by the rhetoric of disruption - but rather “consciously shape a forced transition, or have it imposed at the moment of regulatory or market-driven failure.” Paranoia in the face of a real, credible risk of discontinuation is not an overreaction; it is an accurate assessment of the situation. What is missing is not risk awareness, but a path that treats the transition as a managed capital process rather than a binary cliff edge.

This is precisely where interim, verifiable technical measures - border protection approaches that extend the compliance-compliant service life of existing hardware without a complete redesign - play their true role: not as a permanent substitute for modernization, but as a deliberate deceleration of an otherwise forced, value-destroying disruption into a planned, capital-preserving transition.

One caveat is in order here: The characterization of the technical solution as “a coprocessor solves it” is itself a simplification that this paper does not wish to accept unquestioningly. A hardware-based protective measure eliminates the cryptographic exposure of the affected module. It does not resolve legacy issues - expiring certificate trust chains, firmware update infrastructure built for the old architecture, or other non-cryptographic obsolescence within the same product generation - and it does not, by itself, answer the question of who bears the resulting costs. The following case study is deliberately expanded to highlight these gaps, rather than presenting the technical solution as a complete resolution.

There is another dimension that pure cost accounting does not capture: customer inertia is not an obstacle to be overcome, but rather the actual value being purchased. An OEM customer who selects a component supplier is, to a large extent, purchasing the ability to not have to rearchitect their own system according to the supplier’s schedule. A corrective measure that forces the customer into cascading requalification, redesign, or downtime not only costs money - it breaks the specific promise upon which the original purchase decision was based. From the customer’s perspective, a technically correct solution that forces the customer to disrupt its own operations in order to remain compliant is indistinguishable from the end-of-life that it was actually intended to prevent. To put it plainly, the design goal is not “compliant” - but rather “compliant without forcing the customer to take action.”

4. A Forward-Looking Framework

Breaking the stalemate described in Section 2 - and avoiding the destructive dynamic described in Section 3 - requires treating technical remediation, disclosure practices, and capital planning as a single coordinated timeline, rather than as sequential hand-offs in which each side waits for clarity from the other.

A workable approach relies on three parallel, mutually reinforcing lines of action:

Technical: Creating an inventory against a minimum crypto-agility baseline (dedicated signing hardware, side-channel protection class, PQC-compatible memory headroom). Where a complete redesign within the remaining product lifecycle cannot be economically justified, implementation of interim protective measures - explicitly documented as interim, not presented as a permanent architecture, and, wherever possible, limited to drop-in compatibility with the existing customer interface.
Disclosure Policy: A documented, dated, and funded remediation plan is treated as the primary risk-mitigation measure, since, according to most current regulatory interpretations, a credible remediation timeline reduces risk more effectively than silence.
Capital Planning: Replacing binary “resolved/critical” reporting with milestone-based reporting - staggered budget release tied to demonstrated technical progress, rather than full upfront allocation or withholding funds until complete certainty is achieved.

5. Hard Milestones (illustrative, 24-month horizon)

Time Period	Technical Milestone	Disclosure Milestone	Funding Milestone
Months 1–6	Assessment & risk classification completed	Framework for remediation disclosure established	Base funding released
Months 7–12	Interim safeguards implemented on highest-risk lines	First remediation plan documented	Milestone-linked funding, Tranche 2
Months 13–18	PQC migration piloted for new developments	Proactive regulatory engagement, where applicable	Funding Tranche 3, linked to pilot results
Months 19–24	Crypto agility baseline achieved for prioritized product lines	Compliance status documented for audit	Transition to standard budgeting

6. Concluding Remarks

This framework does not resolve the underlying tension between historical underinvestment and current regulatory deadlines - no framework can retroactively fund three decades of deferred maintenance. What it offers is a way to channel this tension into a limited, controllable, capital-preserving process, rather than an unlimited, value-destroying one. The alternative to a structured path is not the absence of costs - it is the same costs, incurred later, under worse conditions, framed as disruption rather than managed as a transition.

APPENDIX - Illustrative Case Study

The following narrative is fictional and composite. It does not describe a real company, and no resemblance to any named or identifiable organization is intended. It serves to concretely illustrate the framework of this paper, not to report on an actual transformation.

Case: A fictional medium-sized industrial company (“Vantric Industrietechnik GmbH & Co. KG”)

Vantric is a fictional, family-run manufacturer of industrial control and automation components - the kind of high-end medium-sized business commonly found in the German industrial landscape:
approximately 1,400 employees, three generations of family ownership, and a product portfolio consisting of connectivity modules, sensor gateways, and PLC peripherals with typical field lifespans of 12–18 years. Revenue is solid, but margins are thin in a highly competitive OEM supply market. The company is neither large enough to absorb a compliance shock unnoticed nor small enough to escape the regulatory scope.

Month 0 - The Trigger

The trigger was not a security incident. It was a procurement questionnaire from a customer - a Tier-1 automotive supplier - that required, as a standard attachment to the request for proposal, a documented PQC migration roadmap and a CRA declaration of conformity for a gateway module that Vantric had been shipping largely unchanged since 2014. The engineering manager in charge was unable to answer the questionnaire. As it turned out, no one in the entire company could.

Months 1–4 - The Stalemate, Exactly as Predicted

The pattern described in Section 2 of this paper played out almost exactly as described. The head of embedded development, Mr. K., had already pointed out the lack of hardware-isolated key storage in the underlying silicon base two years earlier in an internal memo - filed away, acknowledged, but not funded. Upon reviewing the request for proposals, the legal department recommended not disclosing the gap until “further internal review,” out of concern that any written admission could become evidence in a future liability case. The CFO, faced with a cost estimate that ranged from “manageable” to “existentially threatening” depending on whether a complete redesign or an interim measure was assumed, postponed the decision until the next fiscal quarter - a pattern of delay that the finance team recognized from two earlier, unrelated compliance cycles.

Mr. K. considered resigning. He didn’t, but the internal blame game - “who allowed this to happen?” - consumed most of a quarter that was actually supposed to be devoted to remediation.

Month 5 - The Reframing

What changed was not new information - it was a reframing introduced by an external consultant who had originally been brought in for an independent GDPR matter. He pointed out that the company’s own product lifecycle data (average field service life: 14 years) meant that a complete portfolio redesign was neither necessary nor economically viable for the majority of the affected product line.
About 60% of the units shipped still had a projected remaining service life of 4–7 years - long enough that an interim protective measure (a small, security-hardened coprocessor, to be added during the next scheduled hardware revision) would keep them compliant until the end of their natural life. The remaining 40%, concentrated in newer product lines with a remaining lifespan of over 10 years, did indeed warrant a redesign - but at the normal development pace, not in a panic.

This reframing achieved two things at once: It gave the legal department a defensible, documented position (“a funded, dated remediation plan, differentiated by product cohort”), and it gave the CFO a specific number rather than a range anchored in “existential threat.”

Months 6–18 - Implementation, with Friction

The rollout did not go smoothly. A supplier of the proposed coprocessor experienced a six-week supply bottleneck, which pushed the Q3 milestone back to Q4. A product manager whose bonus was tied to a now-delayed product refresh - unrelated to compliance work - advocated - unsuccessfully - for downgrading the coprocessor development in favor of his roadmap. The works council raised valid questions about whether the interim measure constituted a permanent downgrade in build quality, which required two additional weeks of technical briefings to clarify the matter.

None of this derailed the plan. It delayed it by about one quarter compared to the original 24-month timeline - which the steering committee had deliberately factored in as a buffer from the outset by budgeting 27 months instead of 24, precisely for this reason.

Months 12–20 - Costs Don’t Disappear; They Just Shift

The coprocessor solved the cryptographic capacity issue for the affected gateway module. It did not, however, solve two other problems that arose almost immediately once the solution reached the commercial side of the business.

First, the additional cost increase of €1.85 per unit could not, in practice, be absorbed across the entire customer base - low-margin OEM contracts with multi-year fixed-price commitments meant that the increase either had to be absorbed (which further eroded the already tight margin) or passed on through contract renegotiation. The sales management, faced with the prospect of having to renegotiate fixed-price agreements with several long-standing customers in the middle of their contract terms, openly resisted: The internal argument was not that the solution was wrong, but that “no one sells a security feature that no one asked for at a price premium that no one budgeted for.”
When the price pass-through was announced, two smaller customers demanded competing new quotes instead of simply accepting the increase - one ultimately stayed, citing the documented remediation plan itself as a differentiating factor; the other did not stay and was lost to a competitor who continued to deliver the unupgraded legacy design.

Second, and less visible internally, the solution generated costs on the customer side that Vantrics’ sales team had not originally factored into the discussion. Customers who operated the affected gateways as embedded components of their own certified systems faced their own recertification costs - renewed conformity assessments, in some cases recertification of downstream products that contained the Vantrics module as a subassembly, as well as planning for field retrofits with associated downtime. For customers in regulated industrial environments, this was no trivial burden to pass on; several requested extended transition periods, and one asked directly, “Who’s going to finance this on our end?” - a question to which Vantrics’ sales team had no prepared answer.

The solution, developed over about two additional months of commercial and technical negotiations, was shaped by a requirement that the customer support team had insisted on from the very beginning: Whatever solution was chosen, it had to be drop-in compatible with the form factor, pinout, and firmware interface of the existing gateway. The customers’ own certified systems had been built and certified around Vantrics’ original module; anything that would have forced the customer to modify its own architecture - a new mechanical footprint, a changed communication protocol, a firmware API break - would have shifted the costs from “a single item” to “an entire program” and triggered precisely the kind of cascading re-certification on the customer’s side that no price negotiation could have offset. An early technical proposal - a more powerful but pin-incompatible replacement module - was rejected for this reason alone, even though it would have been cheaper per unit than the coprocessor approach that was ultimately delivered.

The chosen solution - the coprocessor, added during the next scheduled hardware revision - adhered to this requirement precisely because it operated behind the existing interface: from the customer system’s perspective, nothing changed except for a compliance certificate. That was what made the financing discussions with the bank and the tiered pricing with customers viable in the first place - the underlying business case presented to every stakeholder, both internal and external, boiled down to the same sentence: Your operations do not need to change for this to be resolved. Vantric’s existing primary bank agreed to extend the company’s investment credit line specifically against the documented, milestone-based remediation plan - the same plan that had addressed the legal department’s disclosure concerns became the basis for the loan, as it offered the bank a limited, time-bound risk rather than an open-ended one. For the largest affected customers, an optional extended service contract was offered that bundled the hardware update with integration support from Vantric, thereby transforming a pure cost pass-through into a service offering with its own margin. The pricing itself was phased in over the remainder of the contract term rather than applied immediately.

Where the statement “Your operations do not need to change” did not apply - in the case of the discontinued third-party wireless module mentioned below, for which there was no drop-in equivalent - the company was honest that genuine disruption with real cascading costs on the customer side was unavoidable, and treated it as a separate, slower-moving, explicitly labeled exception rather than incorporating it into the smooth narrative of the main program.

This didn’t make the transition free for anyone. It made the costs visible, spread out, and manageable - which is not the same as solved.

Month 24 (effectively Month 27) - Result

Eighteen months after the initial triggering RFP, Vantric submitted a documented, differentiated remediation plan to its key customers - ahead of the customer’s internal deadline and before the 2030 threshold affecting the majority of the affected product cohort. The coprocessor-based interim measure was delivered to the 60% legacy cohort at an additional cost of approximately €1.85 per unit on the bill of materials - compared to an internal estimate that a complete redesign of the same cohort would have cost about 40 times the total budget of the coprocessor program in development hours and re-qualification alone.

Mr. K. did not resign. Eighteen months later, he was granted the budgetary authority he had lacked at the outset - not as a reward, but because the episode had concretely demonstrated that the gap between “Engineering knows” and “Engineering can act” was the actual cost driver, not the underlying technical debt itself.

What This Case Does Not Resolve

The coprocessor program addressed the cryptographic limitation in one product line. The following remained unaffected: the firmware update infrastructure for older field units, which had already been implemented prior to the fix; a separate, still-unresolved issue regarding a discontinued third-party radio module in another product line, for which no equivalent interim measure exists - and where, unlike in the main program, customer disruption could not be avoided and had to be managed as a genuine, cascading exception rather than being smoothed over. Also unaffected was the commercial reality that every unit of cost avoided by an interim measure at Vantric was, in some form, either absorbed by Vantric’s margin, passed on to a customer, or financed as debt - it did not simply disappear.
The case is presented as an illustration of a functional process, not as proof that the underlying costs of decades of deferred investments can be eliminated through technology.

What the Case Illustrates

Nothing about this synthetic case required novel technology, a large budget, or a heroic individual. It required three things that happened in parallel rather than sequentially: an honest, nuanced assessment (not “everything is broken” or “nothing is broken,” but a distribution across cohorts); a culture of disclosure that treats an outdated plan as protective rather than incriminating; and a capital process willing to release funding against milestones rather than demanding complete certainty up front. The friction - supplier delays, internal politics, works council proceedings, sales resistance, customer costs, and the one genuine exception that could not be smoothed over - was real and was deliberately factored in: The framework of this paper is not a guarantee against friction, but merely a structure within which ordinary friction does not become a permanent delay, and within which the disruption that does occur is chosen and planned rather than forced.

> Non-Paper for discussion purposes. Independent analytical perspective.

My Terraform Runner Destroyed Itself Mid-Apply

david — Mon, 03 Aug 2026 09:54:57 +0000

Originally published at woitzik.dev

Disclosure: This post contains Amazon affiliate links (marked with *). If you buy through them, I earn a small commission at no extra cost to you. I only link gear I actually own and use daily.

On 2026-07-04, Atlantis applied a Terraform change that shut down the VM it was running on. The Terraform runner destroyed its own runtime environment mid-apply.

This is the story of a circular dependency that doesn't show up in terraform plan, why bpg/proxmox can't always update attributes in-place, and how moving Atlantis from a k3s Deployment to a dedicated LXC container eliminated the hazard entirely.

View the complete homelab infrastructure source on GitHub 🐙

The Setup

Atlantis was deployed as a k3s Deployment in the apps namespace, running on one of three k3s VMs managed by the same Proxmox Terraform stack. The Proxmox Terraform configuration (terraform/stacks/proxmox/) defines all three k3s VMs, their CPU, memory, disk, and boot settings.

The circular dependency: Atlantis runs on k3s VMs → Terraform manages k3s VMs → Atlantis applies Terraform changes to k3s VMs.

In practice, this was safe for most changes. memory, disk.size, cpu.cores — these can all be updated in-place by bpg/proxmox without stopping the VM. But certain attributes require a full VM shutdown-and-restart cycle. Specifically: cpu.units (scheduling priority) and serial_device configuration.

The Kill Shot

The Terraform diff for a cpu.units change looks like this:

resource "proxmox_virtual_machine" "vm_srv_k3s_11" {
  # ...
  cpu {
    units = 2048  # 2x scheduling priority over LXCs
  }
}

When bpg/proxmox detects a change to cpu.units, it can't hot-apply it. The provider issues a qmshutdown via the Proxmox API, waits for the VM to stop, applies the change, then starts the VM again.

On 2026-07-04, a PR changed cpu.units on one of the k3s VMs. Atlantis picked up the PR, ran terraform plan, showed the diff (in-place update), and ran terraform apply. The bpg/proxmox provider sent qmshutdown to the Proxmox API for the VM running the Atlantis pod.

The VM shut down. The Atlantis pod was killed. The Terraform apply was interrupted mid-execution. Kubernetes rescheduled the pod on a different node, but the apply state was lost.

The same thing happened again on a serial_device attribute change — another attribute that requires a VM shutdown. Two occurrences, same root cause: the Terraform runner was managing the infrastructure it depended on for its own execution.

Why `terraform plan` Doesn't Catch This

The circular dependency isn't expressed in the Terraform configuration. Atlantis's Pod spec doesn't reference the Proxmox VMs, and the Proxmox VMs don't reference Atlantis. Terraform sees two independent resource graphs. The dependency is physical, not declarative — Atlantis runs on the VMs, but Terraform doesn't know that.

terraform plan shows "will update in-place" for cpu.units. It doesn't know that "update in-place" means "shut down the VM first." That behavior is a provider implementation detail, not something Terraform's planning phase understands.

The lifecycle.ignore_changes block can prevent specific attributes from being planned, but that's a workaround, not a fix. You'd be ignoring a real change to avoid a structural hazard.

The Fix: Move Atlantis Off k3s

The fix was ADR-012: move Atlantis from a k3s Deployment to a dedicated LXC container (ct-srv-atlantis-01, VMID 204, IP 10.0.20.250).

# terraform/stacks/proxmox/lxc.tf
resource "proxmox_virtual_machine" "ct_srv_atlantis_01" {
  # Dedicated LXC — NOT managed by the same Terraform stack
  # Atlantis manages OTHER stacks, but its own container is outside the scope
  vm_id   = 204
  name    = "ct-srv-atlantis-01"
  node_name = "pve"
  # ...
}

The key difference: the Atlantis LXC is still defined in the Proxmox Terraform stack, but it's never managed by Atlantis itself. The atlantis.yaml repo config whitelists only specific repos and directories:

repos:
  - name: github.com/dwoitzik/homelab-infrastructure
    allowed_overrides: [apply_requirements, delete_source_branch_on_merge]
    apply_requirements: [approved, mergeable]
    projects:
      - dir: terraform/stacks/network
        workspace: default
      - dir: terraform/stacks/cloudflare
        workspace: default
      - dir: terraform/stacks/garage
        workspace: default

Notice: terraform/stacks/proxmox/ is not listed. Atlantis can plan and apply network, cloudflare, and garage changes — but never Proxmox changes. Proxmox changes go through a separate review process, or I apply them manually after careful review.

This breaks the circular dependency structurally: Atlantis manages everything except the infrastructure it runs on.

The Ansible Layer

The Atlantis LXC runs via Ansible, not k3s:

# ansible/roles/atlantis/tasks/main.yml
- name: Deploy Atlantis via Docker Compose
  community.docker.docker_compose_v2:
    project_src: /opt/atlantis
    state: present

The custom Dockerfile includes the Proxmox self-signed CA cert (pve-root-ca.crt) so Atlantis can talk to the Proxmox API over HTTPS:

FROM ghcr.io/runatlantis/atlantis:v0.30.0
COPY pve-root-ca.crt /usr/local/share/ca-certificates/pve-root-ca.crt
RUN update-ca-certificates

The Proxmox API token, Cloudflare API token, and MikroTik credentials are all stored in Ansible Vault and injected via Docker Compose environment variables.

The Pattern

Any Terraform runner that manages the infrastructure it runs on has this hazard. In a cloud environment, it's less obvious because terraform apply against an Azure VM doesn't restart the VM — Azure handles in-place updates at the platform level. But the same structural dependency exists: an Atlantis instance running on an Azure VM that manages that VM's NSG, disk, or network interface.

The clean fix is always the same: the runner manages everything except itself. If that's not possible, lifecycle { ignore_changes } on attributes that trigger restarts is the minimum viable mitigation.

The same pattern applies to CI/CD runners in enterprise environments. A self-hosted GitHub Actions runner managing its own host's infrastructure via Terraform has the identical circular dependency. The fix is the same: separate the runner's infrastructure from the infrastructure it manages, even if they share the same cloud account.

5 Words that Describe Me

Brian Kim — Mon, 03 Aug 2026 09:54:36 +0000

Brian Kim

5 Words that Describe Me

Determined

I am not one to quit on what I set my goals on. This can be seen through wrestling. Wrestling has been difficult for me both physically and mentally. Since freshman year, my goal was to be in Varsity wrestling. I have lost matches and won matches, so I know it is not always a smooth ride to success. Many hours of training both during season and off season have been dedicated to wrestling. I am determined because I know that hard work will pay off in the end.

Disciplined

Besides just wrestling, I have been a three season athlete for two years. I have participated in cross country, wrestling, and track. These sports have disciplined me in a way that I am able understand without hardships there cannot be any rewards; “no pain, no gain”. In addition, I am mentally disciplined. I know how to balance my priorities between school and sports. Although academics may not be my strong suit, I take it as seriously as the sports I have partaken in.

Reliable

As a team athlete, I need to be reliable. My athletic performance is a good indicator, my wrestling season is one way people put their trust in me. Such as the coaches and my teammates who are there for me during every competition and root for me to win. Furthermore, senior year has been a very ambitious year for me. I have taken several leadership positions and joined a variety of different clubs. For example, I am part of the Kiva club, Odyssey club, Psych club, Flag Football, and the spanish club. These clubs don’t only demonstrate my ambitions, but they represent my reliability and how I can be depended on with a number of different responsibilities.

Motivated

By the number of clubs I’ve joined this year, you could already tell that I am ambitious. However, I’m constantly motivated to do more. In this manner, I have again challenged myself this year to work even harder. My dream is to be a physical therapist. I want to help people and I am motivated to do so. I am currently taking Human Anatomy. Despite the headaches and inconveniences, I am reminded of my goal and I won’t stop until i reach it.

Capable

I am determined, disciplined, reliable, and motivated. To sum it all up, I am capable. I still believe I have much more to prove, yet I am proud of what i have accomplished so far. Quite honestly, my grades freshman year were disappointing. However, my grades have continued to grow from then. I now have 3.36 gpa. Still, I don’t believe this accurately represents what im capable of. I am not the same person i was freshman year. These characteristics are the result of my 4 years at Stevenson, and i intend to pursue a more victorious future in college.

AI Is Great at Reasoning. Stop Using It for Workflows.

Orel Bello — Mon, 03 Aug 2026 09:50:13 +0000

More than a year ago, which is practically ancient history in the AI years, I wrote a blog about using AI to build new self-service capabilities.

It felt like the future.

We built a self-service action that could create new self-service actions, helping us move faster, reduce bottlenecks, and scale a small Platform Engineering team supporting hundreds of developers.

One of the most interesting parts was using Amazon Bedrock to generate Terraform code dynamically at runtime, allowing the system to determine how a new cloud resource should be provisioned using our existing Terraform modules.

It worked.

It was impressive.

And… we removed it.

Looking back, abandoning that approach turned out to be one of the best engineering decisions we made.

At the time, it felt like an isolated technical decision.

It wasn’t.

Recently, we faced a much smaller problem. We wanted to automate the creation of DNS records in Cloudflare through our self-service platform.

The first proposal was exactly what you’d expect today: “Let’s build a Claude Skill.”

Immediately, I had a strong sense of deja vu.

But my hesitation wasn’t about whether AI could do it — it was about whether it should.

We were simply asking the wrong question.

The Industry Shift

A lot of engineers today feel like everything they learned over the last decade suddenly became less relevant.

We are DevOps engineers.

We are Platform Engineers.

We used to spend time designing systems, defining standards, reviewing architectures, and planning before writing a single line of code.

Every automation started with the same question:

“How should we automate this?”

Today, that question has quietly changed. Now we ask:

“How can AI do this?”

At first glance, that sounds like progress. And sometimes it is.
Large Language Models have fundamentally changed the way we build software. Tasks that used to take hours now take minutes, and entire prototypes appear from a single prompt.

The temptation is obvious. If AI can do it… why not let AI do it?

Somewhere along the way, though, many of us unconsciously changed more than just our tools. We changed our engineering process.

Instead of designing the architecture first, we choose the technology first.

The discussion becomes:

“Should we use Claude or GPT?”
“Should this be an Agent?”
“Can Hermes do it?” Before answering a much simpler question:

Does this problem actually need “reasoning”?

Runtime Reasoning vs. Deterministic Execution

People often talk about AI Agents, Skills, MCP servers, and LLM workflows as if they’re simply the next generation of automation.

They’re not.

They solve a different type of problem.

LLMs are great at reasoning through messy, ambiguous problems. They can adapt and change plans. But reasoning adds probability — it’s no longer 100% certain.

That capability is incredibly powerful, but it comes with fundamental tradeoffs. Reasoning, by definition, introduces probability into a process.

Traditional automation is deterministic. Every step is predictable, testable, and produces the same result every single time.

Now let me go back to our DNS example:

Slack Form ──► Lambda ──► DynamoDB ──► Terraform ──► Cloudflare
Nothing in that pipeline required interpretation.

We knew the state we wanted, the code already existed, and the steps were clear. So why introduce a “maybe” into a “definitely” process?

Reason at the Edge. Execute in the Core.

An LLM can be incredibly valuable at the system boundaries. Imagine a developer writing in Slack: “Create a CNAME for api.staging pointing to our new load balancer.”

Turning that natural language sentence into a structured JSON payload is exactly the kind of ambiguity LLMs excel at. Natural language is messy, humans omit context, and intent needs interpretation. That is a genuine reasoning problem.

Structured Outputs solve formatting. They don’t solve decision-making.

The risk is letting a probabilistic model decide which tools to run in production.

Once user intent becomes structured data (or if you collected it via a structured Slack form in the first place), the remaining pipeline no longer benefits from reasoning. Every step after that should behave like standard production software: predictable, testable, and deterministic.

Crucially, the structured data generated by the LLM passes through strict schema validation and deterministic authorization policies (RBAC) in the core. Even if an LLM is manipulated at the edge, it can only request actions — the core independently validates whether the user is authorized to perform them before execution ever touches infrastructure.

The LLM proposes actions.

The platform decides whether they’re allowed.

That realization led us to a clear architectural principle:

Reason at the edge. Execute deterministically in the core.

The Hidden Cost of Runtime Reasoning

Using an AI Skill instead of a workflow seems fast at first, but it creates hidden costs for stability and security.

However, when you introduce runtime reasoning into an execution path, you accept fundamental tradeoffs that directly impact production stability, security, and cost.

Here is how those tradeoffs manifest in production:

Human in the Loop Bottlenecks

If an LLM cannot be trusted to execute production changes unattended, someone must manually review every single run (When it’s open a PR for example).

This brings back the very bottleneck you were trying to fix.

Probabilistic Infrastructure

A script follows orders; an LLM makes choices.

Production isn’t the place to find out the AI made a mistake.

Paying for Unused Intelligence

Scripts cost almost nothing. LLMs cost tokens.

If the workflow was already predictable, you’re paying for “intelligence” you don’t actually need.

Expanding the Attack Surface

A deterministic workflow only executes code you explicitly wrote.

An LLM executes actions based on how it interprets a prompt.

The moment an LLM sits directly in the execution path, prompt injection, context poisoning, and unexpected tool execution become part of your threat model.

For infrastructure, we need predictability, not improvisation.

A script that does the same thing a million times is better than a system that “guesses” correctly most of the time.

Use AI Where It Actually Adds Value
We use AI more than ever — just not to run our production systems.

We use AI to design Terraform modules, generate Lambda functions, build CI/CD pipelines, review Infrastructure as Code, write tests, and understand unfamiliar systems.

Let AI build automation. Don’t let AI be the automation.

Once we’ve reviewed the generated code, the reasoning phase is over.

From that point onward, production executes deterministic software — not prompts. The model participates during development, not in the production control plane.

The AI reasons once. The software runs forever.

The 30-Second Architecture Review
Before introducing an AI Agent, Skill, or runtime LLM into your next system, ask yourself:

[ ] Does this problem actually require runtime reasoning?
[ ] Can every execution step already be described in advance?
[ ] Will the same input always produce the same desired output?
[ ] Could AI generate the workflow code instead of executing it?

If the steps are predictable, you don’t need an LLM. You need reliable software.

Final Thoughts

LLMs are amazing at reasoning, but not every problem needs it.

Use AI to understand what users want and to help you write code. But once the plan is set, let the software take over.

But once your production system knows exactly what needs to happen, stop reasoning and start executing.

User
│

▼

Natural Language
│

▼

LLM (Intent Extraction)
│

▼

Validated JSON
│

▼

Authorization (RBAC / Policies)
│

▼

Deterministic Execution

Lambda ──► DynamoDB ──► Terraform ──► Cloudflare

Reason where things are uncertain. Execute where things are clear.

Because great architecture isn’t about eliminating AI.

It’s about confining uncertainty to the parts of the system that actually benefit from it.

I Built a Language Where AI Calls Are Sandboxed by Default

Harry Machura — Mon, 03 Aug 2026 09:48:25 +0000

I Built a Language Where AI Calls Are Sandboxed by Default

The 30-line Python problem

Last month I needed a script that reads server logs, classifies errors with an LLM, summarizes them, and writes a report. In Python, it looked like this:

Import the SDK
Initialize the client
Handle the API response
Parse JSON
Add asyncio.gather() because sequential calls took 8 seconds
Write a custom sandbox because I don't trust LLMs with exec and file writes
Package it in Docker because requirements.txt always breaks on the server

80 lines later, it worked. But it felt wrong. I wasn't building logic — I was plumbing.

So I asked myself: What if AI operations were language primitives, not library calls?

Meet Pipe

Pipe is a small runtime (~10 MB, single binary, zero dependencies) that treats summarize, translate, classify, and ask as first-class citizens — on the same level as +, sort, or len.

Try it

Browser Playground (WASM, no install): pipe-lang.com

Source: github.com/MachuraHarry/pipe

Docs: pipe-lang.com/docs

Can revenge be heroic?

Brian Kim — Mon, 03 Aug 2026 09:42:20 +0000

Brian Kim

1st Period

Mrs. Lukens

Can revenge be heroic?

Hamlet proves that revenge is heroic, despite it’s evil nature. Through the course of the book, Hamlet restores peace to his kingdom and balances the offenses of King Claudius. Still, Heroism is a matter of perspective and revenge is the action of one’s own justice onto another. What makes revenge heroic is the intent of the one who desires justice, not the aftermath. Hamlet demonstrates his heroism as his revenge begins as an attempt to preserve his fathers honor. His revenge begins heroic, however is later easily corrupted. It is learned, revenge is a never ending cycle and the true heros emerge to be the ones that forgive.

Hamlet’s revenge was justified and therefore heroic. Nevertheless, the changes in him become evident and eventually detract from his righteousness. Hamlet appears to be crazy, although it is said to be merely an act to fool the king, even the reader is unable to distinguish his lunacy as Hamlet was truly blinded by revenge. The first sign of corruption is shown as Hamlet denies his love for Ophelia. Here it is seen, his desire to avenge his father overshadows his love for others. “Get thee to a nunnery. Why wouldst thou be a breeder of sinners?...”(act 3,sc.1), his revenge on Claudius manifests on his conversation with Ophelia. Revenge loses it’s heroism when it changes to hatred. Nevertheless, Hamlets retains his true feelings as he’d rather see Ophelia alone than with another man. Another corruption to heroism in revenge is shown when Hamlet kills Polonius. Hamlet’s revenge does not stop with murder; he now feels nothing and is willing to do whatever it takes to have his revenge. “A bloody deed - almost as bad, good mother, as kill a king and marry his brother”(act 3, sc.4), Hamlet’s revenge has turned evil, yet still portrayed as a justified, almost heroic evil.

With all evils, revenge becomes a never ending cycle. This is shown, following the death of Polonius, in Ophelia. Hamlet’s revenge has spread amongst others including Ophelia and Laertes. Ophelia, for one, is driven to madness and eventually suicide. This shows that revenge is a lose lose situation for both the revenger and the revengee. The cycle continues as Laertes then is manipulated by Claudius and becomes the downfall of Hamlet’s life. Laertes, much like Hamlet, was consumed by his desire to get revenge. Fittingly, Laerte’s plot to kill Hamlet becomes his own death. Still Laertes forgives Hamlet for the murder of his father, “The king, the king’s to blame… he’s justly served. It is poison tempered by himself. Exchange forgiveness with me, noble Hamlet.” Here it is shown again, the backlash of revenge in Claudius as well as the cease of evil through forgiveness. Laertes becomes the true hero as he foils Claudius’s plot and returns honor to Hamlet’s family. Forgiveness emerges to be the best revenge. Forgiveness is pure revenge without corruption..

Moreover, all was not lost in Hamlet’s revenge, Hamlet’s plot appears to be successful. The king has been overthrown and order has returned to the kingdom of Denmark. Hamlet is seen as hero through the way he is buried, “Bear Hamlet like a soldier to the stage...the soldier’s music and the rite of war speak loudly for him.”(act 5, sc.2) Like a martyr, Hamlet does not die in vain. He fulfils his father’s wishes and restores honor and justice in the kingdom. Yet, was it worth it? Hamlet dies pitifully, witnessing the death of his father, mother, and lover.

There is no doubt that revenge is heroic. To enact revenge is to stand up for what one believes in. Still, Hamlet best displays the setbacks of revenge as he dies a pitiful death. Through the course of the book, revenge is revealed to be easily corrupted and shown as a never ending cyle. Forgiveness, on the other hand, is shown as a pure revenge that is not corrupted and finite. Perhaps if Hamlet forgave Claudius, the truth of Claudius’s evil deeds would come back to haunt him. In any case, how we carry on our revenge determines what kind of hero we choose to be.

We crossed 6,000 downloads. Here's what we shipped to get there.

Srinivas Kondepudi — Mon, 03 Aug 2026 09:39:55 +0000

Tuesday morning. Your SOC 2 auditor emails you.

"Can you provide evidence of human review for all AI-assisted code changes in the last 90 days — which files were modified, what prompts were used, and whether any credentials were visible in context?"

You open your IDE. Git log? Commits are there. PR history? Reviews too. But the AI session itself — the conversation, the code it proposed, whether it saw your .env file, which compliance controls it touched — gone.

That gap is why I built Chron.

What Chron is

Chron is an MCP server that runs alongside your AI coding tool. Every message, every code change, every detected secret — locally timestamped, hash-chained, and stored in a SQLite database you own. No cloud. No data sharing. Works offline.

# Install once
npm install -g chron-mcp

# Check setup
chron doctor

Works with Claude Code, Cursor, Windsurf, Continue.dev — any MCP-compatible tool.

The last four releases: answers to questions auditors actually ask

v0.1.39 — "Which sessions are worth reviewing first?"

$ chron risk --since=30d

SESSION           SCORE  BAND      SIGNALS
a1b2c3d4          87     critical  secrets·auth·infra
e5f6g7h8          52     high      auth·findings(2)
i9j0k1l2          28     review    code_changes

The attention score: deterministic 0–100 per session. No ML, no API calls. Pure signal from what actually happened: secrets detected (+25), auth code changed (+15), infra modified (+12), open compliance findings (+8 each). A security lead can triage 90 days of AI sessions in under a minute.

v0.1.40 — "Can I get a one-pager for this audit?"

$ chron dashboard --since=30d --output=q3-audit.html

✓ Written: q3-audit.html
  8 sessions · 4 open findings · 1 critical · 2 high
  Coverage: 6 controls covered · 3 needs evidence

Five sections in a single static HTML file — no server, no login, no port: executive summary, sessions ranked by risk score, findings grouped by framework (SOC 2 / ISO 27001 / EU AI Act / NIST AI RMF), a control coverage map, and contextual next actions. Open in a browser. Print to PDF. Attach to the audit package.

v0.1.41 — "Walk me through this specific session."

$ chron dashboard --session=a1b2c3d4

✓ Written: chron-session-a1b2c3d.html
  Score: 87/100 (critical) · 3 findings · tamper: ✓ ok

The session detail report: attention score breakdown, full timeline with code diffs, secrets with masked values, compliance finding cards with pre-built accept/dismiss CLI commands, which controls the session touches, and a tamper evidence bar (hash chain + NTP clock + Ed25519 signature).

An auditor can open one file and understand what happened, why it matters, which policies it touched, and what action remains — without accessing any internal system.

v0.1.42 — "Is this a one-off, or a pattern?"

$ chron patterns --since=30d

Chron Patterns  last 30d · 8 sessions

●●●● HIGH    Repeated auth/access-control code modified
             4 sessions touched these paths
             · auth, login, rbac, permission…
             Sessions: a1b2c3d4  e5f6g7h8  +2 more

●●●○ MEDIUM  Recurring SOC 2 finding unresolved
             soc2.cc6_1.ai_access_control_change in 2 sessions

●●●○ MEDIUM  Findings unresolved for 28+ days
             3 open findings across 2 sessions

4 patterns detected  2 high  2 medium

Six pattern types: repeated secret exposure, repeated code-signal category changes (auth, infra, AI governance, monitoring), recurring unresolved findings, high-attention recurring sessions, stale findings (configurable: --stale=21).

--json outputs { patterns, session_count } — already shaped for SIEM ingestion in the next release. Pattern IDs are stable keys (repeated_auth_access_control_code_modified, recurring_finding:soc2.cc6_1.*) so SIEM rules can match without parsing titles.

One-off findings are noise. Patterns are risk. This command tells you which is which.

The number

We crossed 6,000 downloads this week. As of publishing: 6,139.

No fundraise. No acquisition. No VC backing. Just a CLI that answers a question nobody had an answer for, installed by 6,000+ developers who needed an audit trail for their AI coding sessions.

What's next

v0.1.43 — SIEM Risk Events: emit pattern_detected, high_attention_session, attention_score_computed events into your pipeline
v0.1.44 — Evidence Connectors: chron evidence import to link policy documents to coverage gaps
Phase 3.5 — Policy Evidence Registry: map your policies to the controls Chron already tracks

Try it

npm install -g chron-mcp
chron doctor

# After a few AI sessions:
chron risk
chron patterns --since=30d
chron dashboard --output=report.html

GitHub: https://github.com/sirinivask/chron

Compressing Video to a Target File Size: The Bitrate Math in TypeScript

Noah Chen — Mon, 03 Aug 2026 09:39:39 +0000

A practical calculator for turning an upload limit into a video bitrate, with enough margin for audio and container overhead.

“Make this video smaller” is an open-ended request. “Make this three-minute video fit under 10 MB” is an engineering constraint.

The second version sounds more precise, but a quality slider alone cannot solve it. A quality setting tells an encoder how aggressively to preserve detail. It does not directly tell us how many bytes the final file may contain. If the destination has a hard upload limit, the useful starting point is a bit budget.

This article builds that calculation in TypeScript, then looks at the assumptions that make the answer less exact than the formula first appears.

File Size Is Bitrate Multiplied by Time

A video file contains several streams plus a container. For a simple MP4, the largest pieces are usually:

the video stream;
the audio stream;
container metadata and indexing overhead.

If we ignore overhead for a moment, the relationship is straightforward:

file size in bits = total bitrate in bits per second × duration in seconds

Rearranging it gives us the total bitrate available for a target size:

total bitrate = target size in bits / duration in seconds

That total must cover both video and audio. The approximate video budget is therefore:

video bitrate = total bitrate - audio bitrate - overhead allowance

The result is not a promise. It is a budget that an encoder can aim at.

Be Explicit About MB and MiB

Before writing code, decide what “10 MB” means.

Storage vendors and many web services use decimal megabytes:

1 MB = 1,000,000 bytes

Operating systems and developer tools often display binary mebibytes:

1 MiB = 1,048,576 bytes

The difference is about 4.9%. That is large enough to turn a file that looks safe locally into a rejected upload. For a hard external limit, I prefer to calculate with decimal MB and keep an additional safety margin. For an internal tool where the unit is clearly MiB, I make that choice explicit in the function name or input type.

A Small TypeScript Calculator

The function below accepts a decimal target size, duration, audio bitrate, container allowance, and safety margin. It returns the video bitrate to pass to an encoder.

type BitrateBudgetInput = {
  targetMB: number;
  durationSeconds: number;
  audioKbps?: number;
  containerOverheadFraction?: number;
  safetyMarginFraction?: number;
};

type BitrateBudget = {
  totalKbps: number;
  usableKbps: number;
  audioKbps: number;
  videoKbps: number;
};

export function calculateVideoBitrate({
  targetMB,
  durationSeconds,
  audioKbps = 96,
  containerOverheadFraction = 0.02,
  safetyMarginFraction = 0.03,
}: BitrateBudgetInput): BitrateBudget {
  if (!Number.isFinite(targetMB) || targetMB <= 0) {
    throw new RangeError("targetMB must be greater than zero");
  }

  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
    throw new RangeError("durationSeconds must be greater than zero");
  }

  const targetBits = targetMB * 1_000_000 * 8;
  const totalKbps = targetBits / durationSeconds / 1_000;

  const reservedFraction =
    containerOverheadFraction + safetyMarginFraction;

  if (reservedFraction < 0 || reservedFraction >= 1) {
    throw new RangeError("reserved fractions must total less than one");
  }

  const usableKbps = totalKbps * (1 - reservedFraction);
  const videoKbps = Math.floor(usableKbps - audioKbps);

  if (videoKbps <= 0) {
    throw new RangeError(
      "The target is too small for this duration and audio bitrate",
    );
  }

  return {
    totalKbps: Math.floor(totalKbps),
    usableKbps: Math.floor(usableKbps),
    audioKbps,
    videoKbps,
  };
}

For a three-minute video with a 10 MB limit:

const budget = calculateVideoBitrate({
  targetMB: 10,
  durationSeconds: 180,
  audioKbps: 96,
});

console.log(budget);

The raw total is roughly 444 kbps. After reserving 5% for overhead and safety, then allocating 96 kbps to audio, the video stream receives about 326 kbps.

That is a tight budget. It may be acceptable for a mostly static 720p screen recording. It will probably look rough for fast camera movement at 1080p. The calculator can tell us whether the numbers fit. It cannot decide whether the visual result is useful.

Add Tests Around the Boundary Conditions

The arithmetic is simple enough that the most valuable tests are about invalid or unrealistic inputs.

import { describe, expect, it } from "vitest";
import { calculateVideoBitrate } from "./bitrate-budget";

describe("calculateVideoBitrate", () => {
  it("returns a positive video budget", () => {
    const result = calculateVideoBitrate({
      targetMB: 25,
      durationSeconds: 120,
      audioKbps: 96,
    });

    expect(result.videoKbps).toBeGreaterThan(0);
    expect(result.videoKbps).toBeLessThan(result.totalKbps);
  });

  it("rejects a zero duration", () => {
    expect(() =>
      calculateVideoBitrate({ targetMB: 10, durationSeconds: 0 }),
    ).toThrow(RangeError);
  });

  it("rejects an impossible audio allocation", () => {
    expect(() =>
      calculateVideoBitrate({
        targetMB: 1,
        durationSeconds: 600,
        audioKbps: 128,
      }),
    ).toThrow(RangeError);
  });
});

An impossible result is useful information. It means at least one constraint must change: shorten the video, increase the file limit, lower the audio bitrate, remove audio, reduce resolution, or accept visibly lower quality.

Why Two-Pass Encoding Gets Closer

A constant bitrate is easy to reason about, but real video does not have constant complexity. A static product screen needs fewer bits than a transition, scrolling page, or camera pan.

Two-pass encoding uses the first pass to analyze where complexity occurs. The second pass spends more of the fixed budget on difficult sections and less on easy ones. It is therefore a sensible choice when file size matters more than encoding speed.

A simplified FFmpeg flow looks like this:

ffmpeg -y -i input.mp4 \
  -c:v libx264 -b:v 326k -pass 1 -an \
  -f mp4 /dev/null

ffmpeg -i input.mp4 \
  -c:v libx264 -b:v 326k -pass 2 \
  -c:a aac -b:a 96k output.mp4

On Windows, the first command uses NUL instead of /dev/null. A production wrapper should also remove the pass-log files and handle failed processes.

Even two-pass encoding can miss an exact target because of muxing overhead, encoder behavior, subtitles, metadata, and rounding. That is why the calculator keeps a safety margin instead of aiming at the final byte.

Codec Choice Changes the Quality, Not the Budget

If the target size and duration are fixed, the total bitrate is fixed too. Switching from H.264 to H.265 does not create a larger bit budget. It tries to produce better visual quality with the same budget.

That tradeoff includes compatibility and encoding cost:

H.264 is widely supported and usually encodes faster.
H.265 can preserve more detail at low bitrates, especially at higher resolutions.
Older browsers, devices, or editing workflows may not handle H.265 as predictably.
Re-encoding an already compressed file can introduce additional artifacts regardless of codec.

For a file that must play everywhere, H.264 may be the safer result. For a controlled playback environment and a severe size limit, H.265 may be worth testing.

Resolution Is Often the Most Honest Lever

At some point, there are not enough bits to describe every pixel well.

Trying to keep 4K resolution at a few hundred kilobits per second usually produces a file that is technically 4K but visually worse than a clean 720p version. Downscaling reduces the number of pixels the encoder must describe and can improve perceived quality at the same file size.

For product videos, I use a simple decision order:

Remove dead time and unnecessary scenes.
Keep only the audio quality the content needs.
Calculate the available video bitrate.
Choose a resolution appropriate for that bitrate and viewing context.
Encode with a safety margin.
Inspect text, cursor movement, transitions, and other high-risk frames.

The final inspection matters. A passing file-size check does not mean small interface text remains readable.

When Not to Build the Pipeline

The TypeScript function is useful when compression is part of a repeatable system: an upload service, media queue, desktop tool, or CI job. In that situation, controlling the encoder and recording the exact settings are worth the engineering effort.

For an occasional file, maintaining that pipeline may cost more time than it saves. A browser-based tool such as VideoCompress exposes target-size and advanced controls without requiring a local FFmpeg workflow. The tradeoff is that processing happens in the cloud, so upload time and data sensitivity matter. Its free account also uses monthly credits rather than offering unlimited processing.

That distinction is the practical one: automate recurring workloads; use a focused interface for one-off work; keep sensitive media local.

Treat the Formula as a Constraint, Not a Quality Score

Target-size compression becomes easier to reason about once the upload limit is translated into a bit budget. The arithmetic tells us what is possible. The encoder decides how to distribute those bits. Human inspection determines whether the result is acceptable.

Those are three separate jobs.

A small calculator prevents impossible settings from reaching the encoder and makes tradeoffs visible before a long job starts. It also replaces the vague instruction to “compress it more” with better questions: Can we shorten it? Can we reduce resolution? Is the audio budget too high? Does compatibility require H.264? Is this recurring enough to automate?

That is usually where a reliable video workflow begins.

A PDF a Human Reads and a Machine Parses at the Same Time: How PDF4me Builds ZUGFeRD E-Invoices

PDF4me — Mon, 03 Aug 2026 09:37:16 +0000

Picture the scenario: your invoicing pipeline generates a clean, branded PDF for a German B2B customer. It looks right. It would print fine, email fine, and satisfy anyone who opens it by hand. Then it bounces, because since January 1, 2025, that customer is legally required to receive invoices in a format their software can parse without a human retyping the totals. A pretty PDF isn't enough anymore, and honestly, for a machine, it never really was the point.

The part that surprises people who haven't dealt with this yet: the mandate doesn't force you to give up the human-readable PDF. It just requires that PDF to carry a second, structured version of itself, riding along inside it. That format is called ZUGFeRD, with an internationally aligned sibling called Factur-X.

If you've never had to build one, it's worth understanding the mechanics before the code, because it's a genuinely clever piece of engineering, not just a compliance checkbox. So how does a single file manage to be both a human-readable invoice and a machine-parseable one at once?

What a ZUGFeRD invoice actually is

Open a ZUGFeRD invoice in Adobe Acrobat or any PDF viewer and you see a normal invoice: logo, line items, totals, payment terms, nothing unusual. But embedded inside that same file, in its attachments, sits an XML document carrying the exact same invoice data in structured, typed form: invoice number, line items, tax rates, totals, every field an accounting system needs, tagged rather than buried in a paragraph a parser has to guess at.

The container format making this possible is PDF/A-3, the only PDF/A variant that permits arbitrary file attachments while still meeting the archival standard's long-term readability requirements. PDF/A-1 and PDF/A-2 explicitly forbid embedded attachments; PDF/A-3 was built for exactly this use case, which is why every ZUGFeRD file you'll open is, underneath, a PDF/A-3b document with an XML file riding inside it.

The embedded XML follows EN 16931, the EU's semantic data model for electronic invoices, with Germany's own XRechnung profile layered on top for domestic traffic. ZUGFeRD has shipped several versions (the 1.0 line through the current 2.x releases), each defining conformance levels, typically BASIC, COMFORT, EXTENDED, and the EN16931-aligned and XRECHNUNG profiles, trading structural strictness for how much invoice detail gets exposed to the machine-readable layer.

This matters most directly for two kinds of teams: anyone generating outbound invoices for German business customers, and anyone receiving invoices who needs to parse the embedded XML straight into an ERP or accounting system instead of manually retyping totals off a PDF.

The two REST primitives underneath it

Strip the standard's name away and ZUGFeRD generation is two REST calls chained together. First, Create PDF/A converts the visible invoice into PDF/A-3b, one of eight conformance levels the endpoint supports (PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2u, PDF/A-2a, PDF/A-3b, PDF/A-3u, PDF/A-3a). Second, Add Attachment to PDF embeds the invoice XML inside that PDF/A-3 shell as a file attachment, the same mechanism you'd use to attach a spreadsheet to a report, just pointed at an XML payload instead. The endpoint's own schema makes this concrete: alongside the top-level docContent and docName for the base PDF, an attachments array holds one object per file to embed, each carrying its own docName (the attachment's filename as it appears inside the PDF, typically invoice-data.xml) and docContent (that file's own Base64 content).

Here's what that looks like live-verified against docs.pdf4me.com, chained end to end:

import requests
import base64

API_KEY = "YOUR_API_KEY"  # Base64-encoded, per PDF4me's Basic auth convention
headers = {
    "Authorization": f"Basic {API_KEY}",
    "Content-Type": "application/json",
}

# Step 1: convert the invoice PDF to PDF/A-3b
with open("invoice.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode()

pdfa_payload = {
    "docContent": pdf_b64,
    "docName": "invoice",
    "compliance": "PdfA3b",
    "allowUpgrade": True,
    "allowDowngrade": True,
}
pdfa_resp = requests.post(
    "https://api.pdf4me.com/api/v2/PdfA", json=pdfa_payload, headers=headers
).json()

# Step 2: embed the invoice XML inside the PDF/A-3b shell
with open("invoice-data.xml", "rb") as f:
    xml_b64 = base64.b64encode(f.read()).decode()

attach_payload = {
    "docContent": pdfa_resp["docContent"],
    "docName": "invoice.pdf",
    "attachments": [
        {"docName": "invoice-data.xml", "docContent": xml_b64}
    ],
}
zugferd_resp = requests.post(
    "https://api.pdf4me.com/api/v2/AddAttachmentToPdf", json=attach_payload, headers=headers
).json()

# zugferd_resp["docContent"] is now the finished ZUGFeRD PDF/A-3b file, Base64-encoded

One honest flag: PDF4me's own Create PDF/A docs page renders its response example inconsistently with every other endpoint here, so double check the exact response key your account actually returns before wiring pdfa_resp["docContent"] into production. Every other call in this chain uses consistent docContent/docName naming, and it's a safe bet Create PDF/A does too, but verify against a real response rather than trusting a docs page's formatting on this one.

Going the other direction, Extract Attachment from PDF does the reverse: hand it a ZUGFeRD PDF, get back the embedded XML as structured data, live-verified as an outputDocuments array of {fileName, streamFile} objects, one per embedded file, exactly what a receiving ERP system needs to actually consume the invoice instead of just archiving it unread.

Knowing this matters even if you never touch the REST API directly. It explains what PDF4me's no-code action is doing under the hood, and it tells you where to look if a generated file doesn't validate the way you expect.

Which approach to reach for depends on how much control the job needs. Calling Create PDF/A and Add Attachment to PDF yourself makes sense if you're already generating the invoice PDF through your own template engine and just need the final embedding step, or if you want to validate the XML against your own schema before it goes anywhere near the PDF. Reaching for Create ZUGFeRD Invoice directly makes more sense the moment you're already living inside Make, Zapier, Power Automate, or n8n for the rest of the invoicing flow, since it collapses both REST calls, plus the conformance-level bookkeeping, into a single configured step you're not maintaining yourself.

The one-action version

Chaining two REST calls yourself is a reasonable way to build this, but PDF4me also ships it as a single purpose-built action, Create ZUGFeRD Invoice, across all four automation platforms this cluster covers. Feed it invoice data as XML, JSON, or CSV, pick a conformance level, and get back a hybrid PDF/A-3 file with the XML embedded and aligned to EN 16931. No manual REST chaining required.

In Make, the action accepts invoice data in any of those three formats and returns the ready-to-send hybrid file. A documented four-module Dropbox workflow walks through the whole thing: pull a base PDF and a ZUGFeRD 2.0+ XML file from Dropbox, run them through Create ZUGFeRD Invoice at EN16931 conformance, push the finished hybrid invoice back to Dropbox.

Zapier's version supports ZUGFeRD 1.0 and the full 2.x line, across BASIC, COMFORT, EXTENDED, EN16931, and XRECHNUNG conformance. Its Dropbox + XML walkthrough triggers on a new file landing in Dropbox, fetches the base PDF and XML payload, runs Create ZUGFeRD Invoice with XmlWithPdf output, and saves the result back to Dropbox at BASIC conformance in the documented example.

Power Automate's action is built explicitly around the German B2B mandate, and pulls source data from SharePoint, OneDrive, Outlook, or Dataverse in addition to XML, JSON, or CSV. Two documented walkthroughs cover the two source-format paths you're most likely to hit: a Dropbox + JSON flow for teams generating invoice data programmatically, and a Dropbox + XML flow for teams that already have ZUGFeRD-formatted XML sitting in a system somewhere and just need it embedded.

n8n's action generates ZUGFeRD 2.0 through 2.4, with EN16931, XRECHNUNG, BASIC, and EXTENDED conformance, from XML, JSON, or CSV. Its Dropbox + JSON walkthrough uploads invoice JSON, runs it through the ZUGFeRD action, and lands the finished file back in Dropbox, with real screenshots of every mapping.

What this doesn't do for you

A structurally valid ZUGFeRD file isn't automatically an invoice your counterparty's accounts-payable system will accept without complaint. Conformance levels exist precisely because different trading partners and national profiles expect different amounts of structured detail, and whether your invoice data actually satisfies EN 16931's business rules is a data-quality question the generation step alone doesn't answer for you. PDF4me's Validate PDF/A action can confirm the PDF/A-3 container itself conforms to ISO 19005, a useful gate before anything ships, though it checks the container, not ZUGFeRD's own business-rule validation of the embedded XML. Build that check into your pipeline before this touches production traffic, not after the first rejected invoice comes back.

Which conformance level to pick isn't really a technical question, it's a contractual one. Ask the receiving business, or their invoicing software vendor, which profile they expect. EN16931 and XRECHNUNG are the two most commonly required for the German mandate specifically, so match what's asked for rather than defaulting to EXTENDED because it sounds more thorough.

Getting started

Every action above sits behind the same PDF4me V2 REST API, so the authentication and base URL story is identical whether you're calling Create PDF/A and Add Attachment to PDF yourself, or letting Create ZUGFeRD Invoice do both in one step through whichever automation platform your team already runs on.

Germany's mandate is the concrete deadline in front of anyone shipping invoices there today. Building the pipeline once, with a tool that already understands PDF/A-3's attachment mechanics, beats re-explaining to a new hire every few months why an invoice PDF has a file attached to it.

Website: pdf4me.com
Documentation: docs.pdf4me.com
Developer portal: dev.pdf4me.com

DEV Community

PDF Tamper Detection API for C#: ASP.NET Core Integration Guide

TL;DR

Prerequisites

Step 1: Test the API with curl

Step 2: Bind Configuration, Not Constants

Step 3: The Result DTO

Step 4: A Typed Exception

Step 5: The Typed HttpClient

Step 6: Register the Client and Retry on Transient Failures Only

Step 7: The Bank-Statement Gate

Step 8: Giving the API a Reachable URL

Step 9: Testing Without Burning Quota

What the Verdicts Mean

What This Does Not Catch

Decisions Before You Ship

Building Coordination Infrastructure: What 32 MCP Servers Without a Bus Look Like

The architectural problem

What a coordination layer looks like at the MCP level

The composable coordination stack

Install

Still Testing APIs Like It's 2022? Here's Everything That Changed"

1. The Tests tab is gone

2. Newman has an official successor

3. Your Jenkins tutorial will not work

4. There's an AI in the footer

5. Your practice APIs died

6. The scripting API moved on politely

7. Secrets got first-class treatment

The takeaway

From Retrospective Liability to Proactive Capability — A Path to Crypto-Agility and Compliance with Embedded Security Requirements

1. Setting the Context

2. Diagnosis, Without Blame

3. The Manufacturing Dimension: Disruption as Capital Destruction

4. A Forward-Looking Framework

5. Hard Milestones (illustrative, 24-month horizon)

6. Concluding Remarks

APPENDIX - Illustrative Case Study

Case: A fictional medium-sized industrial company (“Vantric Industrietechnik GmbH & Co. KG”)

Month 0 - The Trigger

Months 1–4 - The Stalemate, Exactly as Predicted

Month 5 - The Reframing

Months 6–18 - Implementation, with Friction

Months 12–20 - Costs Don’t Disappear; They Just Shift

Month 24 (effectively Month 27) - Result

What This Case Does Not Resolve

What the Case Illustrates

My Terraform Runner Destroyed Itself Mid-Apply

The Setup

The Kill Shot

Why terraform plan Doesn't Catch This

The Fix: Move Atlantis Off k3s

The Ansible Layer

The Pattern

5 Words that Describe Me

Brian Kim

5 Words that Describe Me

Determined

Disciplined

Reliable

Motivated

Capable

AI Is Great at Reasoning. Stop Using It for Workflows.

The Industry Shift

Runtime Reasoning vs. Deterministic Execution

Reason at the Edge. Execute in the Core.

The Hidden Cost of Runtime Reasoning

Final Thoughts

I Built a Language Where AI Calls Are Sandboxed by Default

I Built a Language Where AI Calls Are Sandboxed by Default

The 30-line Python problem

Meet Pipe

Can revenge be heroic?

Brian Kim

Can revenge be heroic?

We crossed 6,000 downloads. Here's what we shipped to get there.

What Chron is

The last four releases: answers to questions auditors actually ask

v0.1.39 — "Which sessions are worth reviewing first?"

v0.1.40 — "Can I get a one-pager for this audit?"

Why `terraform plan` Doesn't Catch This